<html>
<head>
	<title>PicShell</title>
	<LINK rel=stylesheet type="text/css" href="style.css">
	<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
	</script>
	<script type="text/javascript">
	_uacct = "UA-3585962-1";
	urchinTracker();
</script>
<style>
		.main {width:30cm;}



		.mtd {
			padding:0.5cm 0.5cm 0.5cm 0.5cm;
			vertical-align : top;
			border : solid 1px silver;
		}

		th {
			background:#F0F0F0
		}


		</style>

	</style>
</head>
<body><!--	ANNOTATION GUIDE -->
	<center>
		<div class="main">
			<center><span class="title">PicShell - Annotation guide</span></center>

		<div class="sec">
		<br>
		<br>
		<div class="sec2">
		PicShell use annotation to interact with the simulator, for directives, inputs and outputs.
		Annotation has no special meaning for JAL, it's seen as a normal comment.
		<br>Both <span class="annotation">--@</span> or <span class="annotation">;@</span> can be used to specifie annotations

		<br><br><br><br>
		<center><h1>Directives annotation</h1></center>

		<table border=1 style="border-collapse : collapse;border:solid 1px gray" >
				<tr><th>Annotation</th><th>Purpose</th><th>Syntax</th></tr>
				<tr>
					<td class="mtd"><span class="annotation">@use_virtual_delay</span></td>
					<td class="mtd">Tells PicShell to treat delay internally in python, This result in a faster execution for real-time simulation.</td>
					<td  class="mtd" >
					<span class="annotation">;@use_virtual_delay</span><br>
					</td>
				</tr>
				<tr>
					<td class="mtd"><span class="annotation">@no_debug</span></td>
					<td class="mtd">Tells PicShell to not ignore an include while debuging (code is still executed, but will not appear in the JAL debug windows.
					<br><br>
					That can be usefull on "trusted code", if we don't go into the detail of delay implementation for instance.</td>
					<td  class="mtd" >
					<span class="annotation">;@no_debug</span> 16f877_inc<br>
					<br><b>or</b><br>
					<br>
					include pjal_877 <span class="annotation">;@no_debug</span></td>
				</tr>
				<tr>
					<td class="mtd"><span class="annotation">@no_debug_all</span></td>
					<td class="mtd">Tells PicShell to not ignore all includes while debuging (code is still executed, but will not appear in the JAL debug windows.)</td>
					<td  class="mtd" >
					<span class="annotation">;@no_debug_all</span><br>
					</td>
				</tr>
				<tr>
					<td class="mtd"><span class="annotation">@debug</span></td>
					<td class="mtd">Tells PicShell to include an include lib while debuging (only useful in conjonction with @no_debug_all, so that we can tell picshell which lib to include instead of which lib to ignore  )</td>
					<td  class="mtd" >
						<span class="annotation">;@debug</span> 16f877_inc<br>
						<br><b>or</b><br>
						<br>
						include pjal_877 <span class="annotation">;@debug</span></td>
				</tr>

				<tr>
					<td class="mtd"><span class="annotation">@assertEquals</span></td>
					<td class="mtd">Tells PicShell to check a variable value against a reference value</td>
					<td  class="mtd" >
						test(variable_name)<span class="annotation">;@assertEquals</span>  ref_value test_label<br><br>
						<b>Example</b> : See file "examples/unitTest.jal" in your picshell directory.
					</td>
				</tr>
		</table>

		<br><br><br><br>
		<center><h1>Inputs annotation</h1></center>

		<table border=1 style="border-collapse : collapse;border:solid 1px gray" >
			<tr><th>Annotation</th><th>Purpose</th><th>Syntax</th></tr>
			<tr>
				<td class="mtd"><span class="annotation">@mpu</span></td>
				<td class="mtd"><b>M</b>omentary <b>P</b>ull-<b>U</b>p switch<br><img src="img/annotation/mpu.png"></td>
				<td class="mtd" >
					<b>Without alias</b><br>
					<span class="annotation">;@mpu</span> label pin_a0<br>
					<br>
					<b>With an alias :</b><br>
					var bit bt0 is pin_a0 <span class="annotation">;@mpu</span> label
					<br>
					<br>

					<b>Sample code :</b><br>
					<pre>
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@mpu button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == low) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop
					</pre>
					<b>Output : </b><br><img src="img/annotation/mpu_ex.png"><br>
					</td>
			</tr>
			<tr>
				<td class="mtd"><span class="annotation">@mpd</span></td>
				<td class="mtd"><b>M</b>omentary <b>P</b>ull-<b>D</b>own switch<br><img src="img/annotation/mpd.png"></td>
				<td class="mtd" >
					<b>Without alias</b><br>
					<span class="annotation">;@mpd</span> label pin_a0<br>
					<br>
					<b>With an alias :</b><br>
					var bit bt0 is pin_a0 <span class="annotation">;@mpd</span> label
					<br>
					<br>

					<b>Sample code :</b><br>
					<pre>
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@mpd button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == high) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop
					</pre>
					</td>
			</tr>

			<tr>
				<td class="mtd"><span class="annotation">@ppu</span></td>
				<td class="mtd"><b>P</b>ermanent <b>P</b>ull-<b>U</b>p switch<br><img src="img/annotation/ppu.png"></td>
				<td class="mtd" >
					<b>Without alias</b><br>
					<span class="annotation">;@ppu</span> label pin_a0<br>
					<br>
					<b>With an alias :</b><br>
					var bit bt0 is pin_a0 <span class="annotation">;@ppu</span> label
					<br>
					<br>
					<b>Sample code :</b><br>
						<pre>
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@ppu button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == low) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop
						</pre><b>Outputs :</b><br><img src="img/annotation/ppu_ex.png"><br>
					</td>
			</tr>
			<tr>
				<td class="mtd"><span class="annotation">@ppd</span></td>
				<td class="mtd"><b>P</b>ermanent <b>P</b>ull-<b>D</b>own switch<br><img src="img/annotation/ppd.png"></td>
				<td class="mtd" >
					<b>Without alias</b><br>
					<span class="annotation">;@ppd</span> label pin_a0<br>
					<br>
					<b>With an alias :</b><br>
					var bit bt0 is pin_a0 <span class="annotation">;@ppd</span> label
					<br>
					<br>
					<b>Sample code :</b><br>
						<pre>
;@no_debug 16f877_inc
include pjal_877 ;@no_debug
include pic_general ;@no_debug
pragma target clock 4_000_000
pragma target fuses 0x3F32
ADCON1 = 0x07 -- disable A/D

;@ppd button1 pin_a0
;@watch_bin 0x6 port_b

port_A_direction = all_input
port_B_direction = all_output

PORTB = 0
forever loop
	if (pin_a0 == high) then
		PORTB = 1
	else
		PORTB = 0
	end if
end loop

					</td>
			</tr>
			<tr>
				<td class="mtd"><span class="annotation">@pot</span></td>
				<td class="mtd"><b>Pot</b>entiometer</b><br><img src="img/annotation/pot.png">
				<br>
					This component is useful for testing the A/D Converter
				</td>
				<td class="mtd" >
					<b>Without alias</b><br>
					<span class="annotation">;@pot</span> label pin_a0<br>
					<br>
					<b>With an alias :</b><br>
					var bit bt0 is pin_a0 <span class="annotation">;@pot</span> label

					<br>
					<br><b>Example</b> : See file "examples/adc_example.jal" in your picshell directory.
					</td>
			</tr>
			<tr>
				<td class="mtd"><span  class="annotation">@byteSender</span></td>
				<td class="mtd">Send some bytes to the PIC hardware serial UART<br>
					PicShell is somehow limited in this kind of simulation, and is not sensible to the serail settings like baudrate for instance.
				</td>
				<td class="mtd">
					<span class="annotation">;@byteSender</span>&nbsp;<i>(take no parameter)</i><br>
					<br>
					<b>Note : </b>In the user interface, mutliple bytes can be send using the , separator.
				</td>
			</tr>
			<tr>
				<td class="mtd"><span  class="annotation">@asciiSender</span></td>
				<td class="mtd">Same as @byteSender except that the user interface accept text instead of numbers, may be useful for LCD testing</td>
				<td class="mtd"><span class="annotation">;@asciiSender</span>&nbsp;<i>(take no parameter)</i>
				<br>
				<br><b>Example</b> : See file "examples/uart_lcd_example.jal" in your picshell directory.
				</td>
			</tr>
			<tr>
				<td class="mtd"><span  class="annotation">@midiSender</span></td>
				<td class="mtd"><i>Deprecated</i>, A composant that send MIDI "Program change" message. <br>
				<br>
				@byteSender may be used instead as it is more generic.</td>
				<td class="mtd"><span  class="annotation">;@midiSender</span>&nbsp;<i>(take no parameter)</i>
				<br>
				<br><b>Example</b> : See file "examples/midi_in_example.jal" in your picshell directory.
				</td>
			</tr>
			<tr>
				<td class="mtd"><span  class="annotation">@labelIn</span></td>
				<td class="mtd">a simple label, that while stack in the "in" column</td>
				<td class="mtd"><b>Sample usage : </b><span class="annotation">;@labelIn</span>&nbsp;<i>text (optional)</i></td>
			</tr>
		</table>


		<br><br><br><br>
		<center><h1>Outputs annotation</h1></center>

			<table border=1 style="border-collapse : collapse;border:solid 1px gray">
				<tr><th>Annotation</th><th>Purpose</th><th>Syntax</th></tr>
				<tr>
					<td class="mtd"><span  class="annotation">@watch</span></td>
					<td class="mtd">"Realtime" watch to one address, displayed as decimal</td>
					<td class="mtd">
						<span class="annotation">;@watch</span> <i>address</i> <i>label</i>
						<ul>
							<li><i>address</i> : port address
							<li><i>label</i> : a label [optional]
						</ul>
						<b>Sample usage : </b><span class="annotation">;@watch</span> 6 this_is_port_b<br>
						<b>Example : </b>See file "examples/first_example.jal" in your picshell directory.
					</td>
				</tr>
				<tr>
					<td class="mtd"><span  class="annotation">@watch_bin</span></td>
					<td class="mtd">"Realtime" watch on a resister. display as binary</td>
					<td class="mtd">
						<span class="annotation">;@watch_bin</span> <i>address</i> <i>label</i>
						<ul>
							<li><i>address</i> : port address
							<li><i>label</i> : a label [optional]
						</ul>
						<b>Sample usage : </b><span class="annotation">;@watch_bin</span> 6 this_is_port_b<br>
						<b>Example : </b>See file "examples/first_example.jal" in your picshell directory.

					</td>
				</tr>
				<tr>
					<td class="mtd"><span  class="annotation">@watch_hex</span></td>
					<td class="mtd">"Realtime" watch on a resister. display as hexadecimal</td>
					<td class="mtd">
						<span class="annotation">;@watch_hex</span> <i>address</i> <i>label</i>
						<ul>
							<li><i>address</i> : port address
							<li><i>label</i> : a label [optional]
						</ul>
						<b>Sample usage : </b><span class="annotation">;@watch_hex</span> 6 this_is_port_b<br>
						<b>Example : </b>See file "examples/first_example.jal" in your picshell directory.

					</td>
				</tr>
				<tr>
					<td class="mtd">
						<span  class="annotation">@led</span><br>
						<span  class="annotation">@led_red</span><br>
						<span  class="annotation">@led_green</span><br>
						<span  class="annotation">@led_orange</span><br>
						<span  class="annotation">@led_yellow</span><br>
						<span  class="annotation">@led_green</span><br>
						<span  class="annotation">@led_blue</span><br>

					</td>
					<td class="mtd">Display a led<br></td>
					<td class="mtd">
						<span class="annotation">;@led</span> <i>bit</i> <i>label</i>
						<ul>
							<li><i>bit</i> : bit to drive the led (bit can be specified like these : 0x7:4, PORTX:2 or pin_xx)
							<li><i>label</i> : a label [optional]
						</ul>
						<br>
						;@led_red ;@led_orange  ;@led_yellow ;@led_green ;@led_blue<br>
						are same as ;@led,  but use a gif instead of a text<br><br>

						<b>Sample usage : </b><span class="annotation">;@led</span> pin_c0 a_label<br>
						<b>Example : </b>See file "examples/led_example.jal" in your picshell directory.

					</td>
				</tr>
				<tr>
					<td class="mtd"><span  class="annotation">@upDownCounter</span></td>
					<td class="mtd">Counter, that increment on impulsion.<br>Can be used to simulate "digital potentiometers".</td>
					<td class="mtd" >

						<span class="annotation">;@upDownCounter</span> <i>address</i>,<i>enable_bit</i>,<i>impulsion_bit</i>,<i>up_down_bit</i>,<i>max_value</i> <i>label</i><br>
							<ul>
								<li><i>address</i> : port address
								<li><i>enable_bit</i> : allow to have several counter one the same port, if false, the counter won't increment
								<li><i>impulsion_bit</i> : bit used to transmit impulsion
								<li><i>up_down_bit</i> : bit set means increment, bit clear means decrement
								<li><i>max_value</i> : max value where the counter stop to increment. (the counter is not cyclic). min value is 0
								<li><i>label</i> : a label [optional]
							</ul>
						<b>Limitations : </b>all paramters refer to the same address<br>
						<b>Sample usage : </b><span class="annotation">;@upDownCounter</span> 0x6,0,1,2,10 counter1<br>
						<b>Example : </b>See file "examples/counter_example.jal" in your picshell directory.
					</td>
				</tr>
				<tr>
					<td class="mtd"><span  class="annotation">@dual7seg</span></td>
					<td class="mtd">Dual 7 segments display based on a CD4511 / CD4518 driver circuit.</td>
					<td class="mtd">

						<span class="annotation">;@dual7seg</span> <i>address</i>,<i>resetBit</i>,<i>digit1Bit</i>,<i>digit2Bit</i> <i>label</i><br>
							<ul>
								<li><i>address</i> : port address
								<li><i>resetBit</i> : if set display (and internal counter) get back to 00
								<li><i>digit1Bit</i> : bit used to transmit impulsions to increment digit1
								<li><i>digit2Bit</i> : bit used to transmit impulsions to increment digit2
								<li><i>label</i> : a label [optional]
							</ul>

						<b>Limitations : </b>all paramters refer to the same address<br>
						<b>Sample usage : </b><span class="annotation">;@dual7seg</span> 0x6,0,1,2 counter<br>
						<b>Example : </b>See file "examples/dual7seg_example.jal" in your picshell directory.
					</td>

				</tr>
				<tr>
					<td class="mtd"><span  class="annotation">@lcd4bit</span></td>
					<td class="mtd">Limited HD44780, 4bits mode LCD.<br><br>
						<i>This componant is mainly used for internal testing, and is really limited both in fonctionality and configuration for now.</i>
					</td>
					<td class="mtd">
						<span class="annotation">;@lcd4bit</span> <i>address(,nbchar)</i> <i>label</i><br>
						<ul>
							<li><i>address</i> : port address
							<li><i>nbchar</i> : char per line, [optional, default is 16]
							<li><i>label</i> : a label [optional]
						</ul>

						<b>Hardcoded config :</b><br>
						<br>
						<ul>
							<li>HD44780_b4 : <i>address</i>:0
							<li>HD44780_b5 : <i>address</i>:1
							<li>HD44780_b6 : <i>address</i>:2
							<li>HD44780_b7 : <i>address</i>:3
							<li>HD44780_DataCmd : <i>address</i>:4
							<li>HD44780_Enable  : <i>address</i>:5
						</ul>
						<b>Limitations : </b>Only port address is configurable for now<br>
						<b>Sample usage : </b><span class="annotation">;@lcd4bit</span> 0x6 My_LCD<br>
						<b>Examples</b> : "example/lcd_example.jal" and "example/uart_lcd_example.jal" in your picshell directory.
					</td>
				</tr>
				<tr>
					<td class="mtd"><span  class="annotation">@uartReciever</span></td>
					<td class="mtd">Serial reciever that may be used to test UART output.</td>
					<td class="mtd"><span class="annotation">;@uartReciever</span> <i>&nbsp;(take no parameter)</i><br>
					<br>
					<b>Sample usage : </b><span class="annotation">;@uartReciever</span><br>
					<b>Example</b> : "example/midi_out_example.jal" in your picshell directory.
					</td>
				</tr>
			<tr>
				<td class="mtd"><span  class="annotation">@labelOut</span></td>
				<td class="mtd">a simple label, that while stack in the "out" column</td>
				<td class="mtd"><b>Sample usage : </b><span class="annotation">;@labelOut</span>&nbsp;<i>text (optional)</i></td>
			</tr>

			</table>
		</div>
	</div>
	</center>
</body>
</html>